Checklist (check if it applies)

• Contains testing instructions
• Requires environment / credential changes
• Requires special deployment steps
• Has unit / integration tests
• Touches licensing, security, or CI
• License headers on new files (LICENSING.org)
• Attribution preserved on modified files
• Lint passes (npm run lint)
• Security rules followed (SECURITY.org)
• No credentials committed
• All GitHub Checks have passed
• CHANGELOG.org updated (release PRs only)
• Version bumped (release PRs only)

What does this PR do?

Cuts RECKIT v0.3 — the first end-to-end working build — across three commits on websocket-cam-person: the Vue 3 + Vite app with the CAM-LOG overlay and landing index, a full CI gate suite (lint, security scan, license headers, unit tests, and a Pre-Check Failed label sync), and the widget / version / tooling scaffolding that holds it together.

As a content creator running OBS, I want a Vite-served app that exposes every RECKIT browser source under a per-brand URL and a live index page, so that I can add overlays to OBS with a copy-paste URL and see them reflect my scene, mic, and recording state in real time.

Design / Reference: ASCII logo at .github/assets/logo.txt.

Implementation

[NEW] new file · [MOD] modified file · [DEL] removed · [MOV] renamed or relocated

Bootstrap (src/)

• [NEW] main.js — Vue app mount point
• [NEW] App.vue — root <router-view />, loads global SCSS
• [NEW] router.js — brand-routed routes, 404 catchall
• [NEW] shared/config.js — frozen OBS_CONFIG from VITE_* env
• [NEW] shared/version.js — exports VERSION + VERSION_TAG from __APP_VERSION__

Tests (src/**/*.test.js)

• [NEW] shared/version.test.js — semver shape, VERSION_TAG derivation
• [NEW] shared/data/overlays.test.js — registry schema, unique ids, status vocab, use_cases[] type, em-dash ban

Styles (src/app/scss/**)

• [NEW] src/app/scss/** (10 files) — 7-1 SCSS architecture
  • $colors, $typo-scale (x25 steps, 100–800)
  • hud-label-base, cyberpunk-glow mixins
  • brand theming via --clr-* CSS custom properties
• [NEW] src/app/fonts/SpaceMono/ (4 TTFs) — SpaceMono Nerd Font (Regular, Bold, Italic, BoldItalic)

Composables (src/shared/composables/)

• [NEW] use-obs-websocket.js — singleton OBSWebSocket, auto-reconnect, subscribes to All | InputVolumeMeters
• [NEW] use-recording-status.js — RecordStateChanged + take counter + HH:MM:SS formatter
• [NEW] use-audio-analyzer.js — consumes InputVolumeMeters, defaults to Mic/Aux, 8× gain, 16 bars
• [NEW] use-scene-name.js — CurrentProgramSceneChanged

Components (src/shared/components/)

• [NEW] corner-bracket.vue — SVG corner with configurable position, size, stroke_width
• [NEW] hud-frame.vue — 4 corner brackets + 4 labels + slot
• [NEW] overlay-card.vue — landing card with **bold** emphasis parser, use_cases[] chip tags, 2-col spec grid
• [NEW] preview-modal.vue — iframe scaled to canvas aspect ratio via CSS custom property on window.resize
• [NEW] recording-timer.vue — REC + dot turn red while recording; MODE + time stay white
• [NEW] status-indicator.vue — blinking dot (red when active, dimmed white otherwise)
• [DEL] audio-visualizer.vue — superseded by audio-meter widget

Widgets (src/shared/widgets/)

• [NEW] audio-meter.vue — self-contained OBS audio visualizer
  • props: obs, source_name, bar_count
  • emits update:state with { active, source, peak }
• [NEW] live-readout.vue — text display with optional refresh_ms sampling throttle

Overlays (src/brands/kyonax-on-tech/)

• [NEW] cam-person.vue — CAM-LOG HUD at /@kyonax_on_tech/cam-person
  • dynamic top-right label SES::<scene>::T<NN>
  • <audio-meter> bound to Mic/Aux
  • <live-readout> diagnostic line (WS:… | AUDIO:… | L0:…, 200ms throttle)

Overlay registry (src/shared/data/)

• [NEW] overlays.js — CAM-LOG (ready) + ITEM-EXPLAIN (planned) with SHOW / HIDE / CYCLE triggers declared

Landing (src/views/)

• [NEW] home.vue — index with sticky frosted meta bar, brand tabs, responsive 3-col card grid, search + status chips, preview modal

Release

Version: v0.3 (was v0.1)

• [MOD] package.json — "version" bump
• [MOD] README.org — #+VERSION:, ASCII logo footer, and shields.io badge bumped to v0.3
• [MOD] CHANGELOG.org — new [v0.3] entry; TODO refreshed

CI & Tooling

• [NEW] index.html — Vite entry; MPL header added before DOCTYPE (HTML5-safe)
• [NEW] vite.config.js — one config for both Vite and Vitest
  • define: { __APP_VERSION__ } sourced from package.json via createRequire
  • test.environment: 'happy-dom', test.globals: true, test.include: src/**/*.{test,spec}.{js,mjs}
  • v8 coverage provider with HTML + text reporters
• [MOD] .github/workflows/ci.yml — complete CI gate pipeline
  • Triggers: pull_request runs on every target branch (not just master / dev); push fires on feat-* / feat/** / feature/** / fix-* / fix/**
  • Concurrency: group keyed on head_ref || ref with cancel-in-progress: true dedups push-vs-PR double runs and kills stale runs on rapid pushes
  • ESLint: npm ci (lockfile now tracked); lint runs on **/*.{js,mjs,ts} minus node_modules / dist
  • Security Scan: --exclude=eslint.config.mjs + --exclude-dir={node_modules,dist,.cache}; emits ::error file=,line=:: annotations + [category] file:line :: content log lines
  • License Headers: widened to *.vue / *.scss; echoes [MISSING HEADER] <path> per hit + end-of-run summary
  • Unit Tests: new job — npm ci && npm run test (Vitest)
  • Pre-Check Label: final aggregator job, if: always(), reads each gate's result via needs: and toggles the Pre-Check Failed GitHub label with gh pr edit --add-label / --remove-label
  • Permissions: contents: read, pull-requests: write, issues: write (required for label sync)
• [MOD] .gitignore — re-organized by concern; secret-file extension bans (*.pem, *.key, id_rsa*, etc.); !.env.example negation; package-lock.json un-ignored
• [MOD] eslint.config.mjs — __APP_VERSION__ registered as readonly global; Vitest globals (describe, it, test, expect, beforeEach, afterEach, beforeAll, afterAll, vi) enabled on *.test.{js,mjs} / *.spec.{js,mjs} / __tests__/**
• [MOD] package.json — test / test:watch / test:coverage scripts
• [NEW] .env.example — committed template for the OBS WebSocket vars

Dependencies

• Runtime added: vue@^3.5.13, vue-router@^4.5.0, obs-websocket-js@^5.0.6
• Dev added: vite@^6.0.7, @vitejs/plugin-vue@^5.2.1, sass@^1.99.0, vitest@^4.1.4, @vue/test-utils@^2.4.6, happy-dom@^20.9.0
• Upgraded: —
• Removed: —
• Lockfile: package-lock.json now tracked (0 vulnerabilities)

Docs

• [MOD] .github/PULL_REQUEST_TEMPLATE.md — structured layout with embedded format rules

Technical Details

• Audio source pipeline

  • Chose: OBS WebSocket InputVolumeMeters event
  • Over: Web Audio API getUserMedia
  • Why: getUserMedia does not work inside CEF browser sources; OBS gives mixer-accurate levels
  • Trade-off: Requires OBS WebSocket to be running on port 4455

• Reactive state sharing

  • Chose: Module-level singleton for useObsWebsocket
  • Over: Per-component composable instance
  • Why: Every composable needs the same socket; multiple connections would duplicate events and waste resources
  • Trade-off: Cannot mock the connection per component in tests

• Array reactivity across props boundary

  • Chose: ref with a new array assignment per frame
  • Over: shallowRef + triggerRef
  • Why: shallowRef + triggerRef does not propagate to child v-for re-renders across the props boundary
  • Trade-off: Allocates a new array object each analyzer frame (~60/s)

• Preview iframe scaling

  • Chose: Direct CSS custom property mutation (--iframe-scale) on window.resize
  • Over: ResizeObserver-driven reactive computation
  • Why: The observer approach created feedback loops where the scale change triggered a resize event that re-triggered the observer
  • Trade-off: Bypasses Vue reactivity — must remember to update manually if stage size changes outside window.resize

• Version string distribution

  • Chose: Vite define: { __APP_VERSION__ } reading from package.json at config time
  • Over: Hardcoding the version string in each consumer
  • Why: Single source of truth; bumping package.json automatically propagates to every UI surface
  • Trade-off: __APP_VERSION__ must be declared as a readonly global in eslint.config.mjs and imported via src/shared/version.js

• Self-contained widgets vs. primitive components

  • Chose: Two folders — src/shared/widgets/ (self-contained, brand-agnostic drop-ins) and src/shared/components/ (primitives that still need wiring)
  • Over: One shared/components/ folder for everything
  • Why: Widgets let future brands import <audio-meter> without learning the analyzer composable API
  • Trade-off: Developers must pick the right folder; naming rules are in the folder README-by-example

• Overlay description highlighting

  • Chose: **bold** markers parsed into <strong> via String.prototype.matchAll
  • Over: v-html + sanitizer / CMS rich-text field
  • Why: XSS-safe by construction (no HTML parsing); trivial to write in the overlay registry
  • Trade-off: Markdown features limited to bold — no italics, links, or inline code

Testing Coverage

Test runner: Vitest @ 4.1.x with happy-dom and @vue/test-utils
Command: npm run test

Automated tests

Total: 17 tests across 2 files, all passing.

More coverage (composables, widgets, landing computed logic) is tracked as follow-up in CHANGELOG.org under TODO > INFRASTRUCTURE > TESTING.

Quality gates (run on every PR)

How to test this PR

v0.3 release
├─ Setup
│   └─ clone · npm ci · npm run dev
│
├─ Landing page
│   └─ meta bar · search · status chip · modal · copy
│
├─ CAM-LOG in OBS
│   └─ scene · take · recording · audio · offline · version
│
└─ CI sanity
    └─ lint · build · workflows

Setup

Prereqs: repo cloned; Node ≥ 20.

1. Install deps and start the dev server — git checkout websocket-cam-person && npm ci && npm run dev
   Expected: Vite boots on localhost:5173 with no errors in stdout.
2. Copy .env.example to a local env file and populate the OBS WebSocket values.
   Expected: The local env file is listed as ignored by git status.

Landing page

Prereqs: dev server running.

1. Open the index — http://localhost:5173/
   Expected: Sticky meta bar shows SOURCES 2 · BRANDS 1 · READY 1 · CANVAS 1920 × 1080 @ 60; header tag reads RECKIT v0.3.
2. Resize the viewport from ≥ 1200px down to ≤ 400px.
   Expected: Card grid flows 3 columns on desktop, 1 column on mobile; ASCII logo stays centered.
3. Type vlog into the search input.
   Expected: CAM-LOG card matches via its use_cases[] tags; ITEM-EXPLAIN card is hidden.
4. Click the PLANNED status chip.
   Expected: Only ITEM-EXPLAIN is visible; the chip dot is brand-gold only on the active chip.
5. Click OPEN on the CAM-LOG card.
   Expected: Preview modal opens with the overlay iframe scaled to 16:9; pressing ESC or clicking outside closes it.
6. Click COPY on the CAM-LOG card.
   Expected: URL http://localhost:5173/@kyonax_on_tech/cam-person is in the clipboard; button flashes COPIED.

CAM-LOG in OBS

Prereqs: OBS ≥ 32.1.1; WebSocket enabled on port 4455; Mic/Aux audio input unmuted.

1. Add a Browser Source — URL http://localhost:5173/@kyonax_on_tech/cam-person, Width 1920, Height 1080, Custom CSS empty, Shutdown when not visible OFF, Enable Browser Source Hardware Acceleration ON.
   Expected: HUD renders over transparent background with corner brackets, crosshair, identity block, and toolkit-id visible.
2. Rename the current OBS scene.
   Expected: Top-right HUD label updates to SES::<newSceneName>::T01.
3. Start recording, then stop recording.
   Expected: Timer counts in HH:MM:SS; REC text and status dot turn red while recording; MODE: and the time stay white.
4. Start recording again.
   Expected: Take counter increments to T02.
5. Reload the Browser Source.
   Expected: Take counter resets to T01.
6. Speak into the Mic/Aux input.
   Expected: Audio bars respond in real time; debug line reads WS:ON | AUDIO:Mic/Aux | L0:<nonzero> sampling at 5fps.
7. Stop OBS or kill the WebSocket.
   Expected: Auto-reconnect attempt every 5s; OFFLINE HUD label appears; debug line reads WS:OFF | AUDIO:NONE | L0:0.
8. Check the bottom-right of the HUD.
   Expected: Reads RECKIT v0.3.

CI sanity

Prereqs: feature branch pushed to origin.

1. Run lint locally — npm run lint
   Expected: 0 errors; 6 known false-positive warnings on security/detect-object-injection in use-audio-analyzer.js.
2. Run build locally — npm run build
   Expected: Clean build; dist/assets/ populated.
3. Watch PR checks on GitHub.
   Expected: ESLint, Security Scan, License Headers all green.

Special Deployment Requirements

1. OBS environment (CRITICAL) — OBS Studio ≥ 32.1.1 with CEF browser sources and WebSocket enabled on port 4455.
2. Audio routing (CRITICAL) — Mic/Aux input exists and is unmuted; Desktop Audio and browser-source inputs are skipped automatically.
3. Lockfile (REQUIRED) — use npm ci for reproducible installs; never npm install in CI.
4. Release tag (REQUIRED) — after merge to master, run git tag -a v0.3 -m "RECKIT v0.3" && git push origin v0.3.
5. GitHub Release notes (OPTIONAL) — publish a release page using the [v0.3] section of CHANGELOG.org as the body.

Documentation

DESKTOP — Landing page

Index view at 1440px with 3-column card grid and sticky frosted meta bar.

MOBILE — Landing page

Same view collapsed to a single column at 375px.

VIDEO — CAM-LOG overlay running in OBS

Scene change, recording start, Mic/Aux input, recording stop — captured in OBS.

SCREENSHOT — Preview modal

CAM-LOG iframe rendered inside the landing page modal.